home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 9 / Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO / 019a / kws133.zip / KWS.DOC < prev    next >
Text File  |  1993-04-23  |  20KB  |  466 lines
  1.  
  2.  
  3.  
  4.      KWS V1.33 Copyright (c) 1991-1993 Copy Con Incorporated         Page 1
  5.  
  6.  
  7.      DESCRIPTION
  8.      -----------
  9.      KWS (KeyWord Search) is a small, fast program that performs logical
  10.      AND/OR/NOT searches for keywords within one or more text or binary
  11.      files. KWS has many features and options, including:
  12.  
  13.        * Prefix, suffix, and whole word searches.
  14.        * Case-sensitive searches.
  15.        * Adjustable fuzzy searches.
  16.        * Subdirectory searches.
  17.        * Highlight keywords in bold onscreen.
  18.        * Display line numbers or file offset position.
  19.        * Display total lines found per file and per search.
  20.        * Wildcard filename searches.
  21.        * Read data from standard input.
  22.        * Read/write filenames from/to a file list.
  23.        * Search hidden and system files.
  24.        * Stop search after a specified number of matches.
  25.        * Smart pause that detects your screen size.
  26.        * Adjustable window size for searching groups of lines.
  27.        * Display files onscreen while routing to a device or file.
  28.        * Strip control characters from text files.
  29.        * Search/convert text files created on other platforms.
  30.        * Accepts input lines up to 2k in length.
  31.        * Accepts 4DOS 256-character command lines.
  32.        * Runs on any PC compatible using DOS 2.0 or higher.
  33.  
  34.  
  35.      DISCLAIMER
  36.      ----------
  37.      KWS is distributed on an "AS IS" basis without warranty, expressed or
  38.      implied. Considerable testing effort has been expended, but the user
  39.      is advised to check the program's suitability before relying on it.
  40.      The user assumes full risk as to the results of using this program. In
  41.      no event shall the author be liable for any incidental or consequent-
  42.      ial damages arising from the use, or inability to use this program.
  43.  
  44.  
  45.      REGISTRATION
  46.      ------------
  47.      The unregistered version of KWS is freely distributable and fully
  48.      functional, and may be used for a 30-day trial period. If you plan to
  49.      continue using KWS, you are obligated to pay the modest registration
  50.      fee. Registered users will receive a serialized, nag-free version of
  51.      KWS, a free upgrade when available, and $5 subsequent upgrades.
  52.  
  53.      All registration information is contained in the KWS.REG file. If that
  54.      file is missing, register by sending your name and address (please
  55.      print), along with $20 (cash, check, or money order in US funds) to:
  56.  
  57.         Copy Con Incorporated
  58.         PO Box 23255
  59.         Baltimore MD 21203-5255
  60.  
  61.      Please specify 3.5" or 5.25" diskette. MD residents add 5% sales tax.
  62.      Thank you for supporting Shareware.
  63.  
  64.  
  65.  
  66.      KWS V1.33 Copyright (c) 1991-1993 Copy Con Incorporated         Page 2
  67.  
  68.  
  69.      OPERATION
  70.      ---------
  71.      KWS is activated from the command line, using the format
  72.  
  73.         KWS [@]filename search_string[...] [options]
  74.  
  75.      Parameters surrounded by [brackets] are optional.
  76.  
  77.      The @ symbol, if used, must be directly followed by the name of a text
  78.      file containing valid filespecs; the files to be searched will be read
  79.      from that file list. Each filespec in the file list will be searched
  80.      relative to the current directory. (File lists can be created with KWS
  81.      using the /M option; see OPTIONS.)
  82.  
  83.      If the @ symbol is not used, the filename is the filespec to be
  84.      searched. Wildcards are optional. (For a description of wildcards and
  85.      filespecs, see your DOS manual.)
  86.  
  87.      Each search string is comprised of keywords separated by semicolons.
  88.      At least one keyword from each search string must be present in a
  89.      given line for it to be displayed; for example,
  90.  
  91.         KWS allfiles.lst fixed;hard disk;drive
  92.  
  93.      will display the lines in file ALLFILES.LST that contain either words
  94.      FIXED or HARD (or both), and also contain either words DISK or DRIVE.
  95.  
  96.      If a search string contains a keyword with embedded spaces, the entire
  97.      search string must be enclosed in quotes; for example,
  98.  
  99.         KWS temp.bat "del *;era *"
  100.  
  101.      will search TEMP.BAT for phrases "del *" or "era *" (without quotes).
  102.  
  103.      A logical 'NOT' search can be conducted by preceding a keyword with
  104.      an exclamation (!) character; for example,
  105.  
  106.         KWS stuff.txt this !that
  107.  
  108.      will display the lines in STUFF.TXT that contain the word THIS and not
  109.      the word THAT. If you wish to search for an exclamation as the first
  110.      (or only) character of a keyword, use two in a row; for example,
  111.  
  112.         KWS stuff.txt this !!that
  113.  
  114.      will display lines that contain both words THIS and !THAT. Exclamation
  115.      characters inside or following keywords (as in " HEY! " or " What!? ")
  116.      do not have to be doubled.
  117.  
  118.      A fuzzy search can be conducted by preceding a keyword with a tilde
  119.      (~) character; lines with words that are similar to the keyword will
  120.      be displayed. This option is useful if you aren't sure of a keyword's
  121.      correct spelling, or if a keyword may be spelled incorrectly in the
  122.      files to be searched. for example,
  123.  
  124.  
  125.  
  126.      KWS V1.33 Copyright (c) 1991-1993 Copy Con Incorporated         Page 3
  127.  
  128.  
  129.      OPERATION (continued)
  130.      ---------------------
  131.  
  132.         KWS gnu.txt ~copyrite
  133.  
  134.      will display lines with words similar to COPYRITE. (The similarity
  135.      percentage can be adjusted with the /F option; see OPTIONS.) If you
  136.      wish to combine a fuzzy search with a logical 'NOT' search, use the
  137.      'NOT' character before the tilde (as in " !~THE "). Fuzzy searches
  138.      cannot be combined with prefix/suffix/whole word searches (described
  139.      below).
  140.  
  141.      Whole word searches can be conducted by putting underscore (_)
  142.      characters before and after the keyword; for example,
  143.  
  144.         KWS files.lst _c_ source
  145.  
  146.      will display lines in FILES.LST that contain a lone 'C' and the word
  147.      SOURCE. Similarly, prefixes can be searched for by putting an
  148.      underscore before a keyword, and suffixes can be searched for by
  149.      putting an underscore after a keyword. If you wish to search for an
  150.      underscore as the first or last (or only) character of a keyword, use
  151.      two underscores in a row, as with the logical 'NOT' exclamation
  152.      character above. If you wish to combine a prefix/whole word search
  153.      with a logical 'NOT' search, use the 'NOT' character before the
  154.      underscore (as in " !_the_ "). Prefix/suffix/whole word searches
  155.      cannot be combined with fuzzy searches (described above).
  156.  
  157.      Up to 10 search strings are allowed, with up to 10 keywords per
  158.      string.
  159.  
  160.  
  161.      OPTIONS
  162.      -------
  163.      Options can appear anywhere on the command line after the filespec.
  164.      They can be in any order, and are not case-sensitive. Options can be
  165.      separated by spaces (/L3 /P /T) or strung together (/L3/P/T or /L3PT).
  166.  
  167.      Option   Description
  168.  
  169.        /A     When this option is used, all binary files will automatically
  170.               be shown with hexadecimal file offsets.
  171.  
  172.        /B     This option makes the keywords stand out from the rest of the
  173.               displayed line. When using this option, output cannot be
  174.               routed using DOS redirection; use the /O option for output.
  175.  
  176.        /C     Search will be case-sensitive. Case-sensitive searches are
  177.               approximately 20% faster than case-insensitive searches.
  178.  
  179.        /D     Control characters (ASCII value less than 32) within text
  180.               files will be replaced with spaces before being viewed or
  181.               routed.
  182.  
  183.  
  184.  
  185.      KWS V1.33 Copyright (c) 1991-1993 Copy Con Incorporated         Page 4
  186.  
  187.  
  188.      OPTIONS (continued)
  189.      -------------------
  190.        /E     The command line will be echoed as the first output line.
  191.               Useful mainly with redirected files to avoid repetition, and
  192.               for testing batch files.
  193.  
  194.        /Fn    This option controls the similarity percentage for fuzzy
  195.               searches. Similarity defaults to 65 percent, and can be
  196.               adjusted from 0 (display almost every line) to 100 (display
  197.               exact matches).
  198.  
  199.        /H     Hidden and/or system files will also be searched.
  200.  
  201.        /I     Ignore the KWS config file, if present (see CONFIG FILE). If
  202.               stringing options together, make sure that this option is the
  203.               first in the string; for example, use "/ip" instead of "/pi".
  204.  
  205.        /Kc    Change the keyword separator charactor from a semicolon to
  206.               the specified character. This option may be needed to pass
  207.               multiple keyword parameters to a batch file (as some versions
  208.               of DOS remove semicolons from batch parameters), or if a
  209.               semicolon is part of a keyword to be searched.
  210.  
  211.        /L[n]  Line numbers or file offset position will be displayed with
  212.               output. If the specified width begins with a zero, then the
  213.               file offset will be displayed; otherwise, line numbers will
  214.               be displayed. If no width is specified, the numbers will be
  215.               left-justified, with a colon between the number and the text;
  216.               otherwise, the numbers will be right-justified and zero-
  217.               padded to the left, followed by the colon and text. If the
  218.               specified width is too small for a number to fit, the number
  219.               will NOT be truncated.
  220.  
  221.        /M[n]  Stop searching after n matches per file. /M alone will cause
  222.               KWS to print only the filenames of successful searches, and
  223.               these can be redirected to a file to be used as a file list.
  224.  
  225.        /Ofn   Route output to the specified device/filename. Output will be
  226.               in addition to, not instead of, output displayed onscreen. To
  227.               route output without viewing, use DOS redirection instead of
  228.               this option (see your DOS manual for details). Do not append
  229.               other options on to the end of this option, as they will be
  230.               mistaken as part of the device/filename.
  231.  
  232.        /P     Pause between each screen of text. KWS will autodetect your
  233.               screen size, and pause accordingly. While paused, pressing
  234.               the 'C' key will display the current and any remaining files
  235.               continuously. Pressing the Escape key while paused will skip
  236.               the current file and go on to the next. This option will be
  237.               inactive when the /R option is used.
  238.  
  239.  
  240.  
  241.      KWS V1.33 Copyright (c) 1991-1993 Copy Con Incorporated         Page 5
  242.  
  243.  
  244.      OPTIONS (continued)
  245.      -------------------
  246.        /R     Instead of reading from text files, KWS will read from STDIN
  247.               (input is read from an input device or from another program's
  248.               output). When in this mode, the /P and /V options will be
  249.               inactive. Do not specify a filename when using this option.
  250.  
  251.        /S     Subdirectories will also be searched. This option is valid
  252.               only with wildcard and file list searches.
  253.  
  254.        /T[n]  Display total lines found per file. For wildcard and file
  255.               list searches, a grand total will also be displayed. If this
  256.               option is specified as "/t0", then only the totals will be
  257.               displayed, without the corresponding lines.
  258.  
  259.        /V     If KWS cannot determine if a file is binary or text, text
  260.               will be assumed; using this option will tell KWS to treat all
  261.               files as binary. This option is inactive when using the /R
  262.               option; KWS assumes standard input to be text.
  263.  
  264.        /Wn    Normally, all keywords must be on the same line for the line
  265.               to be displayed; use this option to look at more than one
  266.               line at a time. If all keywords are found within the
  267.               specified window size (maximum of 32767 lines), then the
  268.               lines will be displayed, starting with the first line to
  269.               contain a keyword, and ending with the last line to contain a
  270.               keyword. This option is inactive when searching binary files.
  271.  
  272.        /X     When this option is used, line numbers and offset positions
  273.               will be displayed in hexadecimal format instead of decimal.
  274.  
  275.  
  276.      CONFIG FILE
  277.      -----------
  278.      Under DOS 3.0 or higher, a configuration file can be used to specify
  279.      default option values. If a text file named KWS.CFG is in the same
  280.      directory as KWS.EXE, KWS will read default options from the CFG file.
  281.      KWS.CFG consists of one line of text using the format
  282.  
  283.         OPTIONS = [options]
  284.  
  285.      where [options] are the default options. As with command line options,
  286.      case is not important, and the options may be strung together.
  287.  
  288.      Any options enabled in the config file can be disabled on the command
  289.      line by specifying the option with a minus sign appended, and the file
  290.      can be ignored completely by using the /I option. For example, with a
  291.      config file that reads
  292.  
  293.         options=/b /p
  294.  
  295.      bold keywords and screen pausing will be in effect whenever KWS is
  296.      run. To disable bold keywords, "/b-" can be specified on the command
  297.      line. To completely ignore the config file, specify "/i".
  298.  
  299.  
  300.  
  301.      KWS V1.33 Copyright (c) 1991-1993 Copy Con Incorporated         Page 6
  302.  
  303.  
  304.      CONFIG FILE (continued)
  305.      -----------------------
  306.      KWS.CFG must be in the same directory as KWS.EXE. The config file can
  307.      be created with any ASCII text editor, or from the command line by
  308.      typing in the following two lines while in the KWS.EXE directory:
  309.  
  310.         copy con kws.cfg
  311.         options=[options]
  312.  
  313.      where [options] are whatever default options you wish. After typing
  314.      the two lines, press F6 or Control-Z, then press ENTER or RETURN.
  315.  
  316.  
  317.      EXAMPLES
  318.      --------
  319.      KWS catalog.lst dvorak keyboard /p
  320.        will take the lines in file CATALOG.LST that contain the words
  321.        DVORAK and KEYBOARD, and display them one screen at a time (P).
  322.  
  323.      KWS catalog.lst arc;lzh shell /l5 /oprn
  324.        will take the lines in file CATALOG.LST that contain either ARC or
  325.        LZH, and also contain SHELL, and display them onscreen with line
  326.        numbers (L5), while sending them to the printer (OPRN).
  327.  
  328.      KWS allfiles.lst /c !.ZIP >nozip.lst
  329.        will make a file called NOZIP.LST, which will contain all of the
  330.        lines in ALLFILES.LST that do NOT contain the word .ZIP in caps (C).
  331.        Output will not be seen onscreen.
  332.  
  333.      KWS \dl\*.lst MIDI /ptc
  334.        will search all .LST files in the DL directory for the word MIDI in
  335.        capital letters (C), and displays the filenames and lines onscreen,
  336.        one screen at a time (P), with totals (T) for each file.
  337.  
  338.      KWS *.bak _the_
  339.        will search the backup files for lines that contain the word THE,
  340.        but will not display them if THE is part of another word (as in
  341.        THESIS or OTHER).
  342.  
  343.      KWS temp.bak _the_;!_the_ /b
  344.        will display every line in TEMP.BAK, hilighting (B) any occurrance
  345.        of the word THE.
  346.  
  347.      KWS c:\*.bat _del;_era /s/h
  348.        will search all (S) of the batch files on the C: drive, including
  349.        those with their hidden and/or system attributes set (H), to see if
  350.        any of them delete/erase files.
  351.  
  352.  
  353.  
  354.      KWS V1.33 Copyright (c) 1991-1993 Copy Con Incorporated         Page 7
  355.  
  356.  
  357.      EXAMPLES (continued)
  358.      --------------------
  359.      dir | KWS -92 /r
  360.        pipes the output from the DIR command into KWS (R), which will
  361.        display the directory entries from 1992.
  362.  
  363.      KWS ; /r /l3 <one.txt >two.txt
  364.        creates file TWO.TXT which is a duplicate of file ONE.TXT, except
  365.        that TWO.TXT will have 3-digit line numbers (L3). (A search for the
  366.        keyword separator will find every line.)
  367.  
  368.      KWS unix.man ; >unix.doc
  369.        converts a Unix format text file (LF delimited) into a DOS format
  370.        text file (CR/LF delimited). KWS can also read CR delimited files.
  371.  
  372.      KWS *.doc ~copyrite /f70b
  373.        will search the .DOC files for words similar to COPYRITE, hilighting
  374.        any close calls (F70).
  375.  
  376.      KWS *.doc ~copyrite !1993 /f70b
  377.        will display the same lines as the above example, except for lines
  378.        containing the word 1993.
  379.  
  380.      KWS allfiles.lst _c_;assem;asm src;source /pb
  381.        will display all lines in ALLFILES.LST that have to do with C or
  382.        assembler source code. Keywords will be in bold (B), and output will
  383.        be paused after each screen (P).
  384.  
  385.      KWS allfiles.lst _c_;assem;asm src;source !c++ /pb
  386.        will display the same as above, except C++ files will not be shown.
  387.  
  388.      KWS \dl\*.gif GIFLITE /cm
  389.        looks inside of GIF files to see if any have been GIFLITEd, showing
  390.        the filenames (M) of those that have.
  391.  
  392.      KWS \*.com ; /hal6p /od:com.txt
  393.        examines all (even hidden/system) .COM files in the root directory,
  394.        using hex (A) file offsets 6 characters wide (L6), pausing at each
  395.        screen (P), while also sending output to file COM.TXT on the D:
  396.        drive (OD:COM.TXT).
  397.  
  398.      KWS p_simon.txt /cbw2 Ms;Miss;Mrs Robinson
  399.        will do a case-sensitive (C) search for Ms or Miss or Mrs Robinson,
  400.        and will display matches in bold (B), as long as Ms;Miss;Mrs is no
  401.        more than one line's distance (W2) from Robinson.
  402.  
  403.      KWS kws.doc ; /pdolpt2
  404.        displays this file, one screen at a time (P), removing embedded
  405.        formfeed characters (D), while also sending output to printer LPT2
  406.        (OLPT2).
  407.  
  408.  
  409.  
  410.      KWS V1.33 Copyright (c) 1991-1993 Copy Con Incorporated         Page 8
  411.  
  412.  
  413.      EXAMPLES (continued)
  414.      --------------------
  415.      KWS c:\*.bat ; /sm >filelist.txt
  416.        will create a file named FILELIST.TXT containing the names of all
  417.        (S) of the batch files on the C: drive. This file is used in the
  418.        next example.
  419.  
  420.      KWS @filelist.txt label "if %;goto"
  421.        will search the filenames in FILELIST.TXT, and display lines in
  422.        those files that contain the word LABEL and either the word GOTO or
  423.        the phrase "IF %" (without the quotes). Note that this example has
  424.        only two search strings, not three; if any words in a search string
  425.        contain spaces, then the entire search string must be in quotes.
  426.  
  427.  
  428.      RETURN CODES
  429.      ------------
  430.      The DOS errorlevel will be set if a search is unsuccessful:
  431.  
  432.      Level  Description
  433.  
  434.        1    Invalid command line options
  435.  
  436.        2    None of the files contain the search string(s)
  437.  
  438.        3    Ctrl-Break interrupt
  439.  
  440.        4    Invalid directory specified
  441.  
  442.        5    No files match filespec
  443.  
  444.        6    Unable to open output file
  445.  
  446.  
  447.      SUPPORT
  448.      -------
  449.      If you have questions, comments, suggestions, bug reports, et cetera,
  450.      feel free to contact me by one of the following methods:
  451.  
  452.      1: By modem at The Programmer's Corner (301-596-7692 or 410-995-6873).
  453.         Send a message to RD Thomas in the Shareware or General conference,
  454.         and check back in a couple of days for a reply.
  455.  
  456.      2: On a BBS that carries the RIME Shareware conference (RD Thomas,
  457.         node ->1520). Allow at least one week for a reply.
  458.  
  459.      3: By US Mail at the address given on the first page. If you would
  460.         like a reply, please include a self-addressed, stamped envelope.
  461.  
  462.      Looking forward to hearing from you.
  463.  
  464.  
  465.      To print this document, type "COPY KWS.DOC PRN" at the DOS prompt.
  466.